Celestin Apprentice 4

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 4 / Apprentice-Release4.iso / Utilities / Programming / Mac F2C 1.2.2 / Mac F2C Documentation / INSTRUCTIONS (CodeWarrior) < prev next >

Wrap

Text File | 1995-08-29 | 17.7 KB | 390 lines | [TEXT/MMCC]

************************************************* ************************************************* INSTRUCTIONS FOR SETTING UP AND USING Mac F2C WITH METROWERKS CODEWARRIOR C/C++ ************************************************* ************************************************* Before you can use the code produced by Mac F2C, you must set up and build all of the required support libraries. There are also special rules that must be followed when using code produced by Mac F2C. The process and rules are slightly different for Symantec C/C++ or THINK C/C++ and for CodeWarrior C/C++. These instructions are for setting up Mac F2C for use with Metrowerks CodeWarrior C/C++. Refer to the documentation file "Instructions (Symantec)" for instructions on how to set things up for use with Symantec C/C++ or THINK C/C++. USERS UPGRADING FROM VERSION 1.2: The v1.2.2 upgrade has project files and stationary files compatible with CodeWarrior v1.3 (from the CW7 CD). If you are still using CW6, you do not need this upgrade. If you have upgraded to CW7, you only need to replace the old CW6 stationary files with the new CW7 stationary files included here. In theory you do not need to rebuild the support libraries (libI77 and libF77), because the CW6 versions are supposed to work correctly with CW7. Nevertheless, I recommend you build CW7 versions of these libraries using the CW7 project files included with Mac F2C v1.2.2. USERS UPGRADING FROM VERSION 1.1 OR PRIOR: You need to re-install ALL libraries and project files, including main.c and f2c.h. Both library source code and the options settings in the various project files changed. Please note that the source code and libraries provided are set up to use with CodeWarrior v1.3 from the CW7 CD. IF YOU ARE STILL USING CODEWARRIOR V1.2 (CW6): You can find CW6 versions of all the project files and stationary files in the folder "CW6 Project Files" located in the "CodeWarrior Support" folder. Simply replace all the project files and stationary files referred to in these instructions with the corresponding files of the same name from the "CW6 Project Files" folder. To use earlier CodeWarrior releases with Mac F2C, contact Dirk Froehling (dirk@gaga.maschinenbau.uni-dortmund.de), because a few workarounds and additions are required. The instructions here are broken into four sections: A. Setting up Mac F2C B. Verifying correct operation C. Translating with Mac F2C D. Using C code produced by Mac F2C ***************************************************************************** A. SETTING UP Mac F2C ********************** Step 1: BRING ALL THE LIBRARIES UP-TO-DATE The libraries of the Mac F2C distribution come without binaries, so you have to build them according to the following algorithm. There are two versions of each library project, one for the 68K compiler and one for the PowerPC compiler. They are named with the usual extensions, 68K.µ and PPC.µ. You can use both versions or just one if you like (skip the instructions for either the 68K or PPC version). If you are using CW6 vice CW7, replace all the project files and stationary files referred to in these instructions with the corresponding files of the same name found in the folder "CW6 Project Files" located in the "CodeWarrior Support" folder. FOR the project files: (1) "libI77.68K.µ" in the "Mac F2C Libraries" folder (2) "libF77.68K.µ" in the "Mac F2C Libraries" folder (3) "libI77.PPC.µ" in the "Mac F2C Libraries" folder (4) "libF77.PPC.µ" in the "Mac F2C Libraries" folder REPEAT the following steps: (a) Double-click on the project file. (b) In the CW Environment's "Project" menu, select the "Make" command. END REPEAT Step 2: MOVE THINGS TO THE RECOMMENDED LOCATIONS For easiest and smoothest operation, the support libraries and other support files should be installed where the CodeWarrior C compiler can find them easily. I recommend you install Mac F2C libraries and support files as follows: (1) Drag the libraries "libI77.68K", "libF77.68K", "libI77.PPC" and "libF77.PPC" you obtained by following the instructions of Step 1 from the folder "Mac F2C Libraries" to the folder "MacOS Support" in the "Metrowerks C/C++ ƒ" folder that contains the CodeWarrior Environment. I suggest you put them into their own folder inside the "MacOS Support" folder. (CW6 doesn't have a "MacOS Support" folder, so simply place them inside the "Metrowerks C/C++ ƒ" folder.) You can delete the THINK files "libF77", "libI77a", and "libI77b" in the folder "Mac F2C Libraries" if you don't need them. (2) The "For '(Project Stationary)'" located in the "CodeWarrior Specific Stuff" folder contains project stationary files that are used for compiling C and C++ code produced by Mac F2C. Drag the project stationary files to the "(Project Stationary)" folder found in the "Metrowerks C/C++ ƒ" folder that contains the CodeWarrior C/C++ Environment. (3) The "For 'Proj Stationery Support'" located in the "CodeWarrior Specific Stuff" folder contains code files ("f2c.h" and "main.c") that are needed to run C programs produced by Mac F2C. Drag these two files to the 'Project Stationery Support' folder inside the "(Project Stationery)" folder inside the "Metrowerks C/C++ ƒ" folder that contains the CodeWarrior Environment. (CW6 doesn't have a "Project Stationery Support" folder, so for CW6 place "f2c.h" and "main.c" inside the "Metrowerks C/C++ ƒ" folder, preferably in the same place as you put "libI77" and "libF77".) ***************************************************************************** B. VERIFYING CORRECT OPERATION OF Mac F2C ****************************************** The folder "Test Project ƒ" contains the following files: (1) "test.f" -- a sample FORTRAN program. (2) "main.c" -- the main program required to run programs produced by with Mac F2C. (3) "f2c.h" -- an include file required to compile programs produced by Mac F2C. (4) "test.c (Output)" -- what you should get when you translate the sample FORTRAN code files. (5) "Test.68K.µ" and "Test.PPC.µ" -- CodeWarrior projects to run the sample program. These serve as models for how to compile, link, and run C code produced by Mac F2C. (6) "test.c (C++ Output)" -- what you should get when you translate the sample FORTRAN code files and select the C++ output option. (7) "Test++.68K.µ" and "Test++.PPC.µ" -- CodeWarrior projects to run the sample program when Mac F2C is used to produce C++ output. These serve as models for how to compile, link, and run C++ code produced by Mac F2C. (8) "Test.*.π" and "Test++.*.π" -- Symantec/THINK project files (not used) Translate the sample FORTRAN program "Test.f" simply by dragging it onto Mac F2C. Do not change any of the options (use "Factory Defaults"). Once you have done this you can compare it with "Test.c (sample)" file to verify that you got the same thing. If so, double click on the CodeWarrior project "Test.68K.µ" or "Test.PPC.µ" and follow the same steps outlined in the "Bringing Libraries Up-To-Date" section to bring the test project up-to-date. Run it to verify correct operation. If you also plan to use Mac F2C C++ output with the Codewarrior, you can run a second test to verify correct operation with the C++ compiler. Start Mac F2C and in the "C Options" dialog, select "C++ code". Do not change any of the other options. Translate "Test.f". Compare it with "Test.cp (C++ Output)" to verify that you got the same thing. If so, double click on the CodeWarrior project "Test++.68K.µ" or "Test++.PPC.µ" and follow the same steps outlined in the "Bringing Libraries Up-To-Date" section to bring the test project up-to-date. Run it to verify correct operation. ***************************************************************************** C. TRANSLATING FORTRAN PROGRAMS ******************************** You can use Mac F2C to translate FORTRAN to C using four methods: (a) Start up Mac F2C and select the "Translate" command in the File menu. (b) Drag-&-drop a bunch of FORTRAN files onto Mac F2C. (c) Use a scripting language (e.g., AppleScript) to send Mac F2C either an 'open' command, an 'f2c' command, or a 'translate' command. For more information on driving Mac F2C from a script see the instructions in the folder "Mac F2C AppleEvents". (d) Use the MPW/ToolServer tools provided in the "MPW/ToolServer Tools" folder inside the "CodeWarrior Specific Stuff" folder. Please follow the instructions in the "ToolServer READ ME" and "MPW READ ME" files. FORTRAN files must be TEXT files and *must* end in ".f" or ".F" (sorry, but the ending is determined by the unix f2c kernel -- it rejects files handed to it with any other endings). The output file is the same name with a ".c" extension if you selected C code for the output, or the same name with a ".cp" extension if you selected C++ code for the output. The first five items in the Options menu let you control the various translation and code generation options. If you check the "Make these the new defaults" box before clicking the "OK" button, your option selections will be saved in a Preference file and used again the next time you start Mac F2C. If you do not understand what an option means, check the balloon help. The help balloons provide more detailed explanations of what each option means. They also explain why dimmed options are not available and what you can do to make them available. The last item in the Options menu ("Mac F2C Preferences…") lets you control how Mac F2C operates. This dialog lets you control: - How Mac F2C behaves after having been launched with a drag-&-drop. - Whether the "Advanced Options" dialog will have an edit text field that allows you to enter unix option switches directly. - The creator type for all of the output files (determines their icon). - Whether and how Mac F2C interacts with THINK and/or CodeWarrior. If the notify option is checked, Mac F2C will attempt to touch the corresponding THINK or CodeWarrior project file after translating a FORTRAN file into C successfully. If THINK/CodeWarrior is not running or if the file is not part of the current project, Mac F2C will fail silently. If the make option is checked, then Mac F2C will also send a make (e.g., bring up to date) command to THINK/CodeWarrior. If a group of FORTRAN files are translated at once (via a drag-&-drop or via an AppleScript), the make command is not sent until the last file is translated. Again, Mac F2C fails silently if THINK or CodeWarrior can't do it. As in the case of the other option dialogs, check the balloon help if you do not understand what an option means. ***************************************************************************** D. USING C CODE PRODUCED BY MAC F2C ************************************ The C code produced by Mac F2C has the following compile and link requirements: 68K version: - the header file "f2c.h" - the F2C libraries "libI77.68K" and "libF77.68K" - the CW libraries "ANSIFa(4i/8d)C.68K.Lib", "MathLib68K (4i/8d).Lib", "SIOUX.68K.Lib", and "MacOS.lib" - for C++ code only, the CW libraries "ANSIFa(4i/8d)C++.68K.Lib" and "CPlusPlus.Lib" - 4-byte integers - 8-byte doubles - far data - "Smart" code model PPC version: - the header file "f2c.h" - the F2C libraries "libI77.PPC" and "libF77.PPC" - the CW libraries "ANSI C.PPC.Lib", "MWCRuntime.Lib", "Interface.Lib", "SIOUX.PPC.Lib", and "MathLib" - for C++ code only, the CW library "ANSI C++.PPC.Lib" In addition, if you compile a stand-alone FORTRAN program (instead of only some FORTRAN subroutines) you must include "main.c" in your project. This is because the original main routine in the FORTRAN program becomes a function that is called by main.c. In addition, main.c performs a series of initializations (primarily related to error catching) prior to executing the main FORTRAN program. The "For '(Project Stationary)'" and "For 'Proj Stationary Support'" folders provided in the "CodeWarrior Specific Stuff" folder contain everything you need to compile and run code produced by Mac F2C. Copy the project stationary files to the "(Project Stationary)" folder, and copy "main.c" and "f2c.h" from the "For 'Proj Stationary Support'" to the "Project Stationary Support" folder inside the "(Project Stationary)" folder inside "Metrowerks C/C++ ƒ" folder. To start a new project using Mac F2C code, launch the CW 68K or PPC C compiler, select "New Project..." and choose the appropriate Mac F2C project stationary, a name and a folder for your project in the upcoming Standard File dialog. Then add your code files and bring everything up-to-date. Use the "C" versions of project stationary to work with C code generated by Mac F2C and the "C++" versions of project stationary to work with C++ code generated by Mac F2C. If you get any error messages that CodeWarrior could not find "libI77", "libF77", "main.c", or "f2c.h" it means that you did not place these in the appropriate places. Either move them appropriately or adjust the access paths for your project using the CodeWarrior "Preferences..." dialog. If you compile a FORTRAN subroutine or function that you want to call from a C program, look at the output C code to see the appropriate calling protocol. You may or may not need to include the F2C support libraries (libF77 and libI77). In rare cases, you may also need to copy some of the initialization code from "main.c" to your calling program. Please read the following section carefully if you intend to use Mac F2C with the 68K compiler (the PPC compiler doesn't give you any of the options mentioned, so there is nothing to consider): As noted above, code produced by Mac F2C *MUST* be compiled with 4-byte integers. This requirement cannot be relaxed. The other requirements (8-byte doubles, far data) can sometimes be relaxed: - IF you do not use doubles in any situation where their size relative to reals matters (e.g., if you do not use doubles in equivalence and common statements), then your code probably does not require 8-byte doubles. You need to verify this on a case- by-case basis. This requirement exists because Mac F2C follows FORTRAN sizing rules when compiling FORTRAN code: sizeof(real) == sizeof(integer) and sizeof(double) == 2*sizeof(real). FORTRAN real is compiled as C float and FORTRAN double as C double, so doubles have to be 8-bytes long for equivalence and common statements to be properly aligned. There are a few other cases where the size of double variables matters; see AT&T Computing Science Technical Report No. 149 (included with Mac F2C) for a detailed discussion. - IF you compile your program with the option "Local variables are automatic" and you do not have large static data structures, you *might* not need "Far Data". You need to verify this on a case- by-case basis. Mac F2C creates large static data structures for I/O. If you create local variables in the global area (static instead of automatic) or if you have other static data, you will almost certainly require "Far Data". The I/O data structures can be large enough that you may require "Far Data" for that reason alone. - The 68K project files are all set to use the "Smart" code model. That means, the compiler generates a combination of the far and near (32 bit and 16 bit) addressing types, using near when possible. Segments are not limited to 32K of object code. I suggest to stick with this option, since the "Large" code model doesn't usually give you advantages over "Smart", and "Small" requires a jump table for inter-segment jumps which has a negative effect on code size and speed. But you can try and put all files into one segment if your program is small enough and doesn't use much of the library code. You need to verify this on a case-by-case basis. If you are working with very large FORTRAN programs, you may get a link error from Codewarrior saying something to the effect that 16-bit offsets aren't enough to reach some function or other. In this case you can simply select the "Large" code model to solve the problem. If you change the "8-byte doubles", "Smart", "Far Data" or "68881" options, remember to also change them in all the Mac F2C libraries, specifically "libI77.68K" and "libF77.68K", and include the appropriate ANSI library. The standard ANSI library used in the F2C project files is "ANSIFa(4i/8d)C.68K.Lib". The 'Fa' stands for "Far Model" and the arguments inside the braces show the compiler options (4-byte integers/ 8-byte doubles). For example, if you don't need 8-byte doubles, use "ANSIFa(4i)C.68K.Lib"; or if you want direct 68881 support, use "ANSIFa(4i/F/8d)C.68K.Lib". I urge all users to read the enclosed AT&T Computing Science Technical Report No. 149. Consider it your compiler and language reference manual. You can print the report by downloading it to any PostScript printer. You can use Apple's LaserWriter Utility application to do this or you can use any of the many equivalent utilities.